feat(spec): adr-0030-notification-event joins CREATION_ATTESTED_MIGRATION_IDS; its docblock states the ledger-claim matrix (#15710 ruling) - #16068

Fixes #15710

Ruling executed

Director seat, comment 5550131736 on #15710 — maintainer verbatim 「同意」 to decision batch #47 item 5, the question batch #21 had reserved (5491064532, item 3: 「注册进台账时其 applied 状态语义要写清」). Quoted verbatim:

1. Columns. last_run_at is set on every completed non-error run (migrated, already_done, not_applicable); applied_at only on migrated; verified_at is never set by this migration — it has no self-check, and verified_at means a self-check passed. details.outcome carries the four-valued result; an error run writes no ledger claim. The docblock on the constant in packages/spec/src/system/migration.zod.ts states this matrix in place of "silence is not an answer".
2. Receipt, not gate. Nothing gates on the row; it is what an operator reads, in the shape sys-migration.object.ts already documents for the seed-tenancy repair (verified_at: null, blocking: 0 by construction). A gate would need a self-check that does not exist.
3. Creation-attested. A datastore created after the cut-over has no legacy inbox rows by construction — the "true by birth, observably" argument the array's own docblock makes for its two members applies verbatim — so the id joins CREATION_ATTESTED_MIGRATION_IDS, and the three live pins (migration-flag.test.ts:137-139, adr0104-attestation-evidence.test.ts) move with it. Leaving it out would make a fresh store's ledger read "never ran" for a registered id, which is false.

Not reopened: #13998 stands on its historical answer. #14025 is not addressed here — PR #15450 landed the registration, and this card was the successor carrier of the question that registration reserved.

What landed

1. The docblock matrix — NOTIFICATION_EVENT_MIGRATION_ID in packages/spec/src/system/migration.zod.ts

The registration-era paragraph ("silence is not an answer") is replaced by the ruled matrix, written as bullets on the constant (no .describe() text changed; symbols and files cited, never line numbers; provenance in one line — batch #47 item 5, the reserved question from batch #21):

Then "Receipt, not gate" — nothing reads the row as a precondition and nothing may; the shape is the one sys-migration.object.ts documents for the seed-tenancy repair (verified_at: null, blocking: 0), which isDataMigrationFlagVerified answers false to — then the creation-attested paragraph, then one line deferring the run-receipt writer to the runner's lane.

2. CREATION_ATTESTED_MIGRATION_IDS gains NOTIFICATION_EVENT_MIGRATION_ID (third member; existing members and order kept)

The array's docblock now argues the third fact — no legacy sys_notification inbox row here — exactly as it argues the two ADR-0104 facts, and says the attestation row is the same uniform shape as theirs.

⚠️ One reading in the dispatch was corrected against the code, and the docblock states the corrected fact. The dispatch described the fresh store's new row as verified_at: null. attestFreshDatastore (packages/platform-objects/src/system/migration-flag.ts) writes ONE shape for every member — verified_at set at birth, applied_at: null, blocking: 0, details.attested: 'datastore-created-empty' — and the pin the ruling names (migration-flag.test.ts lines 137-141 on main) asserts isDataMigrationVerified is true for every member. So on a fresh store this id's row reads verified BY BIRTH — never by a run, and gating nothing — exactly as the two ADR-0104 rows do. Ruling item 1 governs runs ("never set by this migration"); item 3 puts the id in the array and explicitly moves that pin with it. No runtime writer was changed: a per-id attestation shape would be new contract the ruling does not state (raised as an open question in the report, recommendation: keep the uniform shape).

3. Pins

• NEW packages/spec/src/system/notification-event-migration-ledger.pin.test.ts (14 cases), in the style of ui/action-requires-confirmation-docblock.pin.test.ts (a source-text docblock pin): the literal three-member list in order; the docblock matrix read as bullets — each column's relation, not its wording — plus the retired sentence absent; a self-test feeding the registration-era paragraph to the same readers; and the arbiter: each run receipt (migrated / already_done / not_applicable, verified_at: null) answers false to isDataMigrationFlagVerified, with a control showing the same row with verified_at set answers true.
• packages/platform-objects/src/system/migration-flag.test.ts: the by-construction iterations (lines 137-139, 190, 258, 267, 276) needed no edit; one symbol-named case added — the id is attested at birth in the uniform shape — because an iterating pin stays green with the member gone (the ablation below shows exactly that).
• packages/platform-objects/src/plugin.test.ts: the boot-attestation pins are literal by design — four sorted lists, three toHaveLength(2), and the contradicted-gate case — all moved to three members (adr-0030-notification-event sorts first; the contradicted-gate case now attests the other two ids in array order).
• packages/objectql/src/adr0104-attestation-evidence.test.ts: measured, NOT moved — it never reads the array (it hand-builds attestation rows for the two ADR-0104 gates and asserts the engine's gate reads, which are keyed to those two ids); 19/19 green unchanged. The ruling's "moves with it" did not hold for this file.

4. Changeset

.changeset/notification-event-migration-ledger-claims.md — @objectstack/spec minor, additive: no authorable key, export or accept-set narrows, so the launch-window BREAKING banner does not apply; check:adr-0087-registration judges only declared-breaking changesets (breakingDeclaration: major / **BREAKING / feat!:), so no disposition marker is owed. check:changeset-no-major and check:empty-changeset green.

Runtime side — measured, not changed

The runtime writer of the receipt row is a follow-on card in the runner's lane, filed by the seat on landing. For this PR: no code path writes a sys_migration row for adr-0030-notification-event today (packages/metadata/src/migrations/ has no sys_migration / recordDataMigrationRun / applied_at reference; the three applied_at writers repo-wide are recordDataMigrationRun, attestFreshDatastore and the seed-tenancy backfill, none keyed to this id). No reader gates on it: NOTIFICATION_EVENT_MIGRATION_ID and its literal have zero readers outside packages/spec, and the engine's two ledger gate reads are keyed to the ADR-0104 ids — the stop condition did not trigger. CREATION_ATTESTED_MIGRATION_IDS has exactly one runtime reader, attestFreshDatastore; packages/cli does not read it (the dispatch's M1 was half true).

Verification

Tree 35819dff2 (branch head); spec dist rebuilt from that source (preflight: marker present in 2 built files). Every build/test ran under scripts/pm/os-verify-lock.sh on a shared box; the wrapper's verdict lines are quoted.

• spec: vitest run src/system/migration.test.ts src/system/notification-event-migration-ledger.pin.test.ts — Test Files 2 passed (2), Tests 39 passed (39).
• platform-objects: vitest run src/plugin.test.ts src/system/migration-flag.test.ts — Tests 42 passed (42).
• objectql: vitest run src/adr0104-attestation-evidence.test.ts src/adr0104-lax-deviation-marker.test.ts — Tests 19 passed (19).
• Consumer sweep, DOWNSTREAM direction (...@objectstack/spec, the four packages the seat named plus spec itself): turbo run typecheck over spec, platform-objects, objectql, cli, metadata at --concurrency=2 — Tasks: 61 successful, 61 total (5m40s, shared box; includes spec check:test-typecheck and check:scripts-typecheck, so the new pin file type-checks).
• spec check:generated — ✓ All 15 generated artifacts are up to date: no artifact moved (the const already existed; const TSDoc is not part of the generated docs).
• Gate families derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (5 paths vs merge-base 53cbad9f7): Run reconciliation — 74 derived, 74 run, 0 NOT-MEASURED, 0 UNRUN, every family exit 0. check:doc-authoring (M4) green in both runs.
• Ablation — commit first; restore is git checkout HEAD -- path, proven each leg by hash-object == HEAD blob and an empty git diff HEAD; trap on EXIT/INT/TERM; absolute paths:
  • Leg A, member removed (on-disk: member lines 0, blob hash differs), spec rebuilt, ablation-dist-preflight --absent: marker absent from all 217 built files. Spec pin: 2 failed | 12 passed (the literal list; the type/includes case). platform-objects: 9 failed | 33 passed (the 8 literal pins in plugin.test.ts and the new symbol-named case; the iterating loop stayed green — which is why the literal pins exist).
  • Leg B, the verified_at bullet loses its negation (src-only, on-disk proven): spec pin 1 failed | 13 passed, exactly the verified_at case.
  • Final: restored, rebuilt, preflight: marker present in 2 built files, spec pin 14 passed (14), platform-objects 42 passed (42), tree clean.

Declared to CI: turbo ls --affected against 53cbad9f7 lists 75 packages (everything depends on spec); locally this diff can move only the consumer tests over the migration-flag / attestation files and the typecheck of spec's named consumers, which is what ran. The rest of the farm is CI's.

Out of scope

• The runtime writer of the run receipt — the seat's follow-on card in the runner's lane.
• Filed as a finding, attestFreshDatastore names os migrate value-shapes as the remedy for every contradicted id that is not files-to-references — with a third creation-attested id the ternary is a wrong remedy on a path nothing reaches yet #16067: attestFreshDatastore's contradiction warning names os migrate value-shapes for every id that is not files-to-references; unreachable for the third member today (the engine keys admitted violations by the two ADR-0104 ids only), so not touched here.

🤖 Generated with Claude Code

Generated by Claude Code